docs: add docs/ scaffolding with ADR and runbook conventions#7
Merged
Conversation
Establish the docs/ structure as the canonical location for project documentation that bridges business need and technical reality. Adds: - docs/README.md: tech spec template covering overview, goals/non-goals, current state, solution, constraints, open questions, and glossary. - docs/adrs/: architectural decision records using an extended Michael Nygard format (Title, Status, Context, Decision, Consequences, Alternatives Considered). Includes README documenting when to write an ADR, the lifecycle, and numbering conventions. - docs/runbooks/: operational runbook template optimized for high-stress reading. Includes README codifying when to write one and the maintenance discipline (review-on-use, quarterly audit). Each subdirectory contains both a curated README index and a template file. Templates use the same blockquote convention as the rest of the repository (delete-after-instantiation). This is the foundation for follow-up work: Makefile generation targets (make adr / make runbook), CI-enforced docs hygiene (adr-lint with pre-commit and GitHub Actions integration), staleness detection, and broader documentation automation. Those land in subsequent commits to keep this change reviewable in isolation.
Add .tool-versions as the source of truth for runtime versions, with Makefile bootstrap detection and CONTRIBUTING.md updates to recommend mise to new contributors. Changes: - .tool-versions: template file with conventions documented inline. All entries commented out; projects derived from this template uncomment the lines they need. - Makefile: HAS_TOOLVERSIONS detection, bootstrap step that runs mise install (or asdf as fallback) when .tool-versions is present, graceful degradation with instructional message when neither tool is installed. - CONTRIBUTING.md: prerequisites updated to recommend mise as the primary version manager. Existing language-specific manifests (package.json engines, pyproject.toml, etc.) are kept but framed as derivative of .tool-versions. Eliminates the duplication of version specs across CONTRIBUTING.md, CI workflows, Dockerfiles, and language manifests. Bumping a tool version becomes a single-file change.
…ssions The previous commitlint.yml combined PR title validation and commit message validation in a single workflow under pull_request_target. This caused two problems: 1. The amannn/action-semantic-pull-request action failed with "Resource not accessible by integration" because the workflow was missing the statuses: write permission required to post check results back to the PR. 2. The commits job ran under pull_request_target while explicitly checking out the PR head SHA. This is the pwn-request pattern: PR-author-supplied code (commitlint config, npm install scripts) would execute with the workflow's elevated permissions, allowing a malicious PR to compromise the repo. Splits the validation into two workflows with appropriate triggers and permission scopes: - pr-title.yml: pull_request_target, reads PR metadata only, posts status check. Safe because the action never executes PR code. - commit-lint.yml: pull_request, checks out PR code in its own reduced-permission context. The check result is the workflow exit code, no API write needed. Branch protection rules should be updated to require both checks: "PR Title Lint / PR title" and "Commit Lint / Commit messages". The old "Commit Lint / PR title" and "Commit Lint / Commit messages" check names will no longer exist.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Establish the docs/ structure as the canonical location for project documentation that bridges business need and technical reality.
Adds:
Each subdirectory contains both a curated README index and a template file. Templates use the same blockquote convention as the rest of the repository (delete-after-instantiation).
This is the foundation for follow-up work: Makefile generation targets (make adr / make runbook), CI-enforced docs hygiene (adr-lint with pre-commit and GitHub Actions integration), staleness detection, and broader documentation automation. Those land in subsequent commits to keep this change reviewable in isolation.
Todos
Deploy Notes (optional)
Notes regarding deployment the contained body of work.
Steps to Test or Reproduce (optional)
Outline the steps to test or reproduce the PR here.
commands to test PRImpacted Areas in Application (optional)
List general components of the application that this PR will affect: